Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume18 / parseargs / patch04a next >

Wrap

Internet Message Format | 1991-04-25 | 50.9 KB

From: brad@hcx1.ssd.csd.harris.com (Brad Appleton) Newsgroups: comp.sources.misc Subject: v18i101: parseargs - functions to parse command line arguments, Patch04a/4 Message-ID: <1991Apr26.035651.18697@sparky.IMD.Sterling.COM> Date: 26 Apr 91 03:56:51 GMT Approved: kent@sparky.imd.sterling.com X-Checksum-Snefru: aa10b441 0172f42d 2638fed9 93182d90 Submitted-by: Brad Appleton <brad@hcx1.ssd.csd.harris.com> Posting-number: Volume 18, Issue 101 Archive-name: parseargs/patch04a Patch-To: parseargs: Volume 17, Issue 45-57 This is patch04 for parseargs. It is a four part patch that you will need to unshar in order. It fixes some major bugs, a few minor ones, and corrects some more errors in the documentation. Two new files are given here (patchlevel.h & doc/effects.inc). Two old files are resubmitted (Makefile & doc/Makefile) amd two patchfiles are included (PATCH and DOCPATCH). ______________________ "And miles to go before I sleep." ______________________ Brad Appleton Harris Corp., Computer Systems Division Software Engineer 2101 West Cypress Creek Road, M/S 161 brad@ssd.csd.harris.com Fort Lauderdale, FL 33309-1892 USA ...!uunet!hcx1!brad Phone: (305) 973-5360 ~~~~~~~~~~~~~~~~~~~~ Disclaimer: I said it, not my company! ~~~~~~~~~~~~~~~~~~~ #!/bin/sh # This is a shell archive (produced by shar 3.49) # To extract the files from this archive, save it to a file, remove # everything above the "!/bin/sh" line above, and type "sh file_name". # # made 04/24/1991 21:50 UTC by kent@sparky.IMD.Sterling.COM # # existing files WILL be overwritten # # This is part 1 of a multipart archive # do not concatenate these parts, unpack them in order with /bin/sh # # This shar contains: # length mode name # ------ ---------- ------------------------------------------ # 66103 -rw-rw-r-- DOCPATCH # 4610 -rw-rw-r-- Makefile # 79034 -rw-rw-r-- PATCH # 2667 -rw-rw-r-- doc/Makefile # 1060 -rw-rw-r-- doc/effects.inc # 2409 -rw-rw-r-- patchlevel.h # if test -r _shar_seq_.tmp; then echo 'Must unpack archives in sequence!' echo Please unpack part `cat _shar_seq_.tmp` next exit 1 fi # ============= DOCPATCH ============== echo 'x - extracting DOCPATCH (Text)' sed 's/^X//' << 'SHAR_EOF' > 'DOCPATCH' && *** /hx1d3/lp/brad/parseargs_patch03/parseargs/argtype3.txt Wed Apr 10 09:55:51 1991 --- argtype3.txt Mon Apr 15 08:31:00 1991 *************** *** 42,51 **** X called when an argument of that particular type is matched X by one of the argument parsing function in parseargs(3). X When such an argument is matched, its argument translation ! routines is invoked and is passed (1) the address of the X argument descriptor for the matched argument, (2) the possi- X ble argument string for that matched argument, and (3) a ! boolean filed that is TRUE only if the second parameter X points to temporary storage (indicating that some copying X may need to be done instead of just pointing to the same X object). --- 42,51 ---- X called when an argument of that particular type is matched X by one of the argument parsing function in parseargs(3). X When such an argument is matched, its argument translation ! routine is invoked and is passed (1) the address of the X argument descriptor for the matched argument, (2) the possi- X ble argument string for that matched argument, and (3) a ! boolean field that is TRUE only if the second parameter X points to temporary storage (indicating that some copying X may need to be done instead of just pointing to the same X object). *************** *** 229,235 **** X followed by the type of the items in the vector. X X SEE ALSO ! parseargs(3), parseargs(3), parsecntl(1), X X X --- 229,235 ---- X followed by the type of the items in the vector. X X SEE ALSO ! parseargs(3), parseargs(1), parsecntl(3) X X X *** /hx1d3/lp/brad/parseargs_patch03/parseargs/parseargs1.txt Wed Apr 10 09:55:52 1991 --- parseargs1.txt Mon Apr 15 08:31:18 1991 *************** *** 9,19 **** X parseargs - parse command line arguments in shell scripts X X SYNOPSIS ! parseargs [-U] [-M] [-T string] [-F string] [-A] [-a arg- ! spec] [-e name] [-f file] [-l] [-o] [-s shell] ! [-u] [-i] [-p] -- name [arguments ...] X X OPTIONS X -U just print program usage, do not parse the X command line X --- 9,22 ---- X parseargs - parse command line arguments in shell scripts X X SYNOPSIS ! parseargs [-#UMCAlouip1] [-S separator] [-T string] ! [-F string] [-a arg-spec] [-e name] [-f file] ! [-s shell] -- name [arguments ...] X X OPTIONS + -# just print the version and patchlevel, do not + parse the command line + X -U just print program usage, do not parse the X command line X *************** *** 20,25 **** --- 23,31 ---- X -M just print (n|t)roff -man manual page X template, do not parse the command line X + -S separator field-separator-string used to delimit array + elements (default= + X -T string string to use for true boolean arguments X (default=``TRUE'') X *************** *** 26,31 **** --- 32,40 ---- X -F string string to use for false boolean arguments X (default=``'') X + -C Ignore the difference between upper and lower + case when parsing single character options. + X -A modify array behavior for the specified shell. X X -a arg-spec argument specification string *************** *** 48,76 **** X X -p prompt the user for missing required arguments X - -i ignore bad command-line syntax and continue - processing (instead of aborting) X - ARGUMENTS - -- Indicates that any remaining options are - intended for the calling program. X - name name of calling program X X X X - Page 1 X X X X X X ! PARSEARGS(1) PARSEARGS(1) X X X X arguments arguments to calling program X X DESCRIPTION --- 57,89 ---- X X -p prompt the user for missing required arguments X X X X + Page 1 X X X X X X + PARSEARGS(1) PARSEARGS(1) X X X ! -i ignore bad command-line syntax and continue ! processing (instead of aborting) X + -1 Force any and all non-positional parameters to + be specified before any positional parameters + on the command-line. X + ARGUMENTS + -- Indicates that any remaining options are + intended for the calling program. X + name name of calling program + X arguments arguments to calling program X X DESCRIPTION *************** *** 98,131 **** X on standard output that is suitable for input to nroff or X troff using the -man macro package. X X The argument specification string contains one entry for ! each possible flag. Entries in the arguments specification X string are separated by commas. Each entry has five comma- X separated fields: a name, some flags, a type, a variable- X name, and a prompt. Each of these fields are described X below: X - name The single character name of the associated flag. - For example, to indicate that the program is - expecting a ``-x'' flag, this field would contain - 'x'. Positional arguments (those without a ``-x'' - prefix) are indicated by passing a ``space'' - character. X - flags Flags modifying the semantics of this entry. - These should have one of ARGREQ to indicate a - required argument or ARGOPT to indicate an - optional argument (ARGOPT is the default unless - ARGREQ is specified). ARGPOS can be ``ored'' in - to indicate a positional argument that may also be - keyword matched. ARGNOVAL can be ``ored'' in to - indicate that an argument is an option or a - keyword that does not use an accompanying argument - (such as a boolean flag). This flag is only - required for corresponding argument types that are X X - X Page 2 X X --- 111,131 ---- X on standard output that is suitable for input to nroff or X troff using the -man macro package. X + Given no other arguments parseargs -# prints on standard + output, the current version and patchlevel of the running + version of parseargs. + + X The argument specification string contains one entry for ! each possible flag. Entries in the argument specification X string are separated by commas. Each entry has five comma- X separated fields: a name, some flags, a type, a variable- X name, and a prompt. Each of these fields are described X below: X X X X X Page 2 X X *************** *** 137,154 **** X X X ! implemented by the programmer; parseargs already ! knows which pre-defined argument types take an ! argument. ARGVALOPT can be ``ored'' in to X indicate that an argument to the option may be X optionally supplied on the command-line, but is ! not required. ARGVALREQ can be ``ored'' in to X indicate that an argument to the option is X required (this is the default behavior for options ! that take arguments). ARGLIST can be ``ored'' in X (using the `|' character) to indicate that an X argument is actually a list of one or more ! arguments from the command line. ARGHIDDEN can be X ``ored'' in to indicate a flag that should not be X printed in usage messages - for example, flags X intended for internal debugging purposes. --- 137,165 ---- X X X ! name The single character name of the associated flag. ! For example, to indicate that the program is ! expecting a ``-x'' flag, this field would contain ! 'x'. Positional arguments (those without a ``-x'' ! prefix) are indicated by passing a ``space'' ! character. ! ! flags Flags modifying the semantics of this entry. ! These should have one of ARGREQ to indicate a ! required argument or ARGOPT to indicate an ! optional argument (ARGOPT is the default unless ! ARGREQ is specified). ARGPOS may be ``ored'' in ! to indicate a positional argument that may also be ! keyword matched. ARGVALOPT may be ``ored'' in to X indicate that an argument to the option may be X optionally supplied on the command-line, but is ! not required. ARGVALREQ may be ``ored'' in to X indicate that an argument to the option is X required (this is the default behavior for options ! that take arguments). ARGLIST may be ``ored'' in X (using the `|' character) to indicate that an X argument is actually a list of one or more ! arguments from the command line. ARGHIDDEN may be X ``ored'' in to indicate a flag that should not be X printed in usage messages - for example, flags X intended for internal debugging purposes. *************** *** 177,194 **** X The argument specification string must be terminated by the X single string: ``ENDOFARGS''. X - Note that the comma character (',') is used to separate all - fields within an entry, and to separate the entries - themselves. For this reason, no field in any entry may - contain a comma unless it appears inside of double or single - quotes. X - Parseargs will parse all command-line arguments for the - calling script and match them against the argument - specification string provided. The argument specification - string is read from standard input by default but may not - come from a terminal. The argument specification string may - be supplied as a single string argument by using the -a X X X --- 188,194 ---- *************** *** 203,208 **** --- 203,220 ---- X X X + Note that the comma character (',') is used to separate all + fields within an entry, and to separate the entries + themselves. For this reason, no field in any entry may + contain a comma unless it appears inside of double or single + quotes. + + Parseargs will parse all command-line arguments for the + calling script and match them against the argument + specification string provided. The argument specification + string is read from standard input by default but may not + come from a terminal. The argument specification string may + be supplied as a single string argument by using the -a X ``string'' flag. Long argument specification strings X however, may limit the number of arguments to the script if X there is a limit to the number of arguments and/or *************** *** 244,263 **** X string option. The same may also be done for a boolean flag X that is false using the -F string option. X - Parseargs will only set the values of variables that - correspond to arguments that were given on the command line. - If a particular argument was not supplied on the command - line, then no assignment is made for the corresponding shell - variable and it will have the same value that it had before - parseargs was invoked. The only exception to this is that if - the -u option is specified, then the positional parameters - are unset before any shell variable assignments (which may - reset the positional parameters) are made. X X - - - X Page 4 X X --- 256,263 ---- *************** *** 269,274 **** --- 269,284 ---- X X X + Parseargs will only set the values of variables that + correspond to arguments that were given on the command line. + If a particular argument was not supplied on the command + line, then no assignment is made for the corresponding shell + variable and it will have the same value that it had before + parseargs was invoked. The only exception to this is that if + the -u option is specified, then the positional parameters + are unset before any shell variable assignments (which may + reset the positional parameters) are made. + X The double-dash (``--'') which precedes the name and X arguments of the calling program is needed in order for X parseargs to be able to distinguish options to itself from *************** *** 280,285 **** --- 290,310 ---- X options) are to be permitted by specifying the -o (-l) X option on the command-line. X + SPECIFYING PARSE-BEHAVIOR + The -C, -p, -i, and -1 switches may be used to modify the + command-line parsing behavior of the invoking script. + Specifying -C will cause case-differences in single- + character options to be ignored. Specifying -p will cause + the user to be interactively prompted for any missing + required arguments. Specifying -i will cause syntactically + incorrect arguments to be ignored (instead of having a usage + message printed and execution terminated). Specifying -1 + will force all non-positional parameters to precede any + positional parameters on the command-line (hence anything on + the command-line after a positional parameter that resembles + a keyword parameter will nevertheles be interpreted as a + positional parameter). + X OPTIONS WITH OPTIONAL ARGUMENTS X Options that may take an optional argument need special X consideration. The shell programmer needs to know whether *************** *** 297,302 **** --- 322,340 ---- X the shell variable associated with the option in the X argument description string. X + + + Page 5 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X ARGUMENT LISTS X Parseargs treats ARGLIST arguments in a special way. The X method used for setting up an argument list depends largely *************** *** 321,340 **** X positional parameters of the calling program will be re- X assigned to the contents of the argument list. X - - - - Page 5 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X For the Plan 9 shell (rc), if the variable name X corresponding to the ARGLIST argument is ``*'', then the X positional parameters of the calling program will be re- --- 359,364 ---- *************** *** 344,349 **** --- 368,374 ---- X ARGLIST argument is ``ARGV'', then the positional parameters X of the calling program will be re-assigned to the contents X of the argument list. + X Bourne Shell Argument Lists X X For the Bourne shell, if the associated variable name is NOT *************** *** 356,362 **** X contains an IFS character (such as a space or a tab), then X that particular word will be treated by the Bourne shell as X two distinct words. - X Also for the Bourne shell, If the associated variable name X is NOT ``--'' and the -A option WAS specified, then that X variable is treated as the root name of an array that is set --- 381,386 ---- *************** *** 363,368 **** --- 387,406 ---- X using the following syntax: X name1='arg1' X name2='arg2' + + + + Page 6 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X ... X and the variable ``name_count'' will be set to contain the X number of items in the array. The user may then step *************** *** 387,406 **** X overwritten by the set command). X It should be noted that there is a bug in versions of the X Korn shell earlier than 11/16/88a, in which the following: - - - - Page 6 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X set -A name 'arg1' 'arg2' ... X causes the positional parameters to be overwritten as an X unintentional side-effect. If your version of the Korn shell --- 425,430 ---- *************** *** 409,414 **** --- 433,439 ---- X must save them yourself before you call parseargs. This may X be accomplished by the following: X set -A save_parms "$@" + X C and TC Shell Argument Lists X X For the C and TC shells, ARGLIST variables are treated as *************** *** 418,436 **** X in $name[2], etc ..., and all items may be given by $name. X Notice that Korn shell arrays start at index zero whereas C X and TC shell word-lists start at index one. - X Bourne-Again Shell Argument Lists X X At present, the Free Software Foundation's Bourne-Again X shell is treated exactly the same as the Bourne Shell. This X will change when bash supports arrays. X Plan 9 Shell Argument Lists X X For the Plan 9 shell, if the associated variable name is not ! ``*'' then it is considered to be word-list and set using X the following syntax: X name=( 'arg1' 'arg2' ... ) - X Awk Argument Lists X For awk, if the -A option is not given, then the output for X thes variable-list will be a line with the variable name, --- 443,474 ---- X in $name[2], etc ..., and all items may be given by $name. X Notice that Korn shell arrays start at index zero whereas C X and TC shell word-lists start at index one. X Bourne-Again Shell Argument Lists X X At present, the Free Software Foundation's Bourne-Again X shell is treated exactly the same as the Bourne Shell. This X will change when bash supports arrays. + X Plan 9 Shell Argument Lists X X For the Plan 9 shell, if the associated variable name is not ! ``*'' then it is considered to be a word-list and set using ! ! ! ! Page 7 ! ! ! ! ! ! ! PARSEARGS(1) PARSEARGS(1) ! ! ! X the following syntax: X name=( 'arg1' 'arg2' ... ) X Awk Argument Lists X For awk, if the -A option is not given, then the output for X thes variable-list will be a line with the variable name, *************** *** 442,448 **** X If the -A option is given, then the associated variable is X considered the root name of an array. The ouput for the X array will consist of two lines for each item in the list ! (as in the following expample): X name1 X arg1 X --- 480,486 ---- X If the -A option is given, then the associated variable is X considered the root name of an array. The ouput for the X array will consist of two lines for each item in the list ! (as in the following example): X name1 X arg1 X *************** *** 452,477 **** X and the variable ``name_count'' will have an output line X showing the number of items in the array. X - - - - - Page 7 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X Perl Argument Lists X X For perl, each argument list is considered an array and is X set using the following syntax: ! @name=( arg1 , arg2 , ... ); X A Final Note on Argument Lists X X The word-lists used by the C shell, the arrays used by the --- 490,501 ---- X and the variable ``name_count'' will have an output line X showing the number of items in the array. X X Perl Argument Lists X X For perl, each argument list is considered an array and is X set using the following syntax: ! @name=( 'arg1' , 'arg2' , ... ); ! X A Final Note on Argument Lists X X The word-lists used by the C shell, the arrays used by the *************** *** 495,500 **** --- 519,538 ---- X ARGLISTs and ARGVECs set in ``CMD_ARGS'' will be appended X from the command-line if they are selected). X + + + + Page 8 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X It is important to note that the contents of the X ``CMD_ARGS'' environment variable are NOT expanded by the X shell and hence any special characters (such as quotes or *************** *** 519,538 **** X of parsecntl(3). The user may set his (or her) own desired X parsing behavior through the use of the ``PARSECNTL'' X environment variable. By indicating any number of flags - - - - Page 8 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X (possibly negated) the user will directly modify the X behavior of the parseargs library. Flags may be combined by X placing a `+' or `|' character in between flags. A switch is --- 557,562 ---- *************** *** 551,570 **** X Ignore X Ignore any unrecognized or improperly specified X command-line arguments and continue execution of the ! program. Normally, if an argument is unmatched (or is ! improperly specified), a usage message is printed and ! program execution is terminated. X X OptsOnly X Under UNIX, setting this flag will disable the parsing X of long-option syntax. This will cause all arguments ! starting with '+' to always be treated as a positional X parameter (instead of a long-option). X X KwdsOnly X Under UNIX, setting this flag disables the parsing of X single-character options. This will cause all ! arguments starting with '-' to always be treated as a X positional parameter (instead of an option). X X LoptsOnly --- 575,608 ---- X Ignore X Ignore any unrecognized or improperly specified X command-line arguments and continue execution of the ! program. Normally, if a required argument is unmatched ! (or an argument is improperly specified), a usage ! message is printed program execution is terminated. X X OptsOnly X Under UNIX, setting this flag will disable the parsing X of long-option syntax. This will cause all arguments ! starting with `+' to always be treated as a positional X parameter (instead of a long-option). X + + + + Page 9 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X KwdsOnly X Under UNIX, setting this flag disables the parsing of X single-character options. This will cause all ! arguments starting with `-' to always be treated as a X positional parameter (instead of an option). X X LoptsOnly *************** *** 585,609 **** X one positional argument. X X CaseIgnore X - - - Page 9 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - - Setting this flag causes character-case to be ignored - when attempting to match single-character argument - names (i.e. causes "-i" and "-I" will be considered - equivalent). - X If the environment variable ``PARSECNTL'' is empty or X undefined, then the parsing behavior set by the programmer X is used. If the programmer has not explicitly used --- 623,633 ---- X one positional argument. X X CaseIgnore + Setting this flag will cause character-case to be + ignored when attempting to match single-character + argument names (i.e. causes "-i" and "-I" to be + considered equivalent). X X If the environment variable ``PARSECNTL'' is empty or X undefined, then the parsing behavior set by the programmer X is used. If the programmer has not explicitly used *************** *** 627,638 **** X only a command-line synopsis is printed (this is also X refferred to as ``terse'' mode). The other two ``modes'' X control the displaying of option syntax and long-option - syntax. A mode may be explicitly disabled by preceding its - corresponding string with the `!' character. The ``modes'' - which correspond to the possible values of the ``USAGECNTL'' - environment variable are given by the following table. X X X Quiet X No usage message of any kind is displayed. X --- 651,676 ---- X only a command-line synopsis is printed (this is also X refferred to as ``terse'' mode). The other two ``modes'' X control the displaying of option syntax and long-option X X + + Page 10 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + + syntax. A mode may be explicitly disabled by preceding its + corresponding string with the `!' or `-' character. The + ``modes'' which correspond to the possible values of the + ``USAGECNTL'' environment variable are given by the + following table. + X Quiet X No usage message of any kind is displayed. X *************** *** 651,670 **** X Description X The command description is printed. X - - - - Page 10 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X Terse X Terse mode, just print command-line synopsis. X --- 689,694 ---- *************** *** 680,685 **** --- 704,710 ---- X KeyWords X Same as LongOpts. X + X If the environment variable ``USAGECNTL'' is empty or X undefined, then the default usage level (which is presently X ``Verbose + Options'') will be used. *************** *** 689,697 **** X specification for a Bourne shell script: X X #!/bin/sh - X RepCount=2; X Verbose=""; X ARGSPEC=" X 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}', X 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}', --- 714,736 ---- X specification for a Bourne shell script: X X #!/bin/sh X RepCount=2; X Verbose=""; + + + + + Page 11 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X ARGSPEC=" X 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}', X 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}', *************** *** 701,708 **** X ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}', X ENDOFARGS X " X - eval `echo "$ARGUMENTS" | parseargs -s sh -- $0 "$@"` X X This describes a Bourne shell script accepting up to three X flag arguments and one or two positional arguments, plus a --- 740,747 ---- X ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}', X ENDOFARGS X " + eval `echo "$ARGSPEC" | parseargs -s sh -- $0 "$@"` X X X This describes a Bourne shell script accepting up to three X flag arguments and one or two positional arguments, plus a *************** *** 717,736 **** X FALSE (an empty string). X X -X A Boolean ``X Rated'' flag. This is not - - - - Page 11 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X printed in the usage message. X X The two positional arguments are both strings, as is the --- 756,761 ---- *************** *** 758,763 **** --- 783,802 ---- X associated command line variables, and then prints its X command usage. X + + + + Page 12 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X #!/bin/sh X # test.sh - Bourne shell script to test out the parseargs command! X # *************** *** 783,802 **** X X ## parse command-line and save assignments in a temporary file ## X parseargs -s sh -e ARGUMENTS -u -- "$NAME" "$@" >/tmp/tmp$$ - - - - Page 12 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X if [ $? -ne 0 ] X then rm -f /tmp/tmp$$; exit 2 ## non-zero status (usage given) X fi --- 822,827 ---- *************** *** 825,838 **** X Parseargs may exit with one of the following status codes: X X X -1 Some type of system error occurred during execution, X causing the program to exit prematurely. X X 0 Normal exit status (no problems were encountered). X ! 1 The calling program specified the -U or the -M option ! to parseargs, or specified an argUsage flag on the ! command line. Only the appropriate message is X displayed. X X 2 A command line syntax error was encountered by --- 850,876 ---- X Parseargs may exit with one of the following status codes: X X + + + Page 13 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X -1 Some type of system error occurred during execution, X causing the program to exit prematurely. X X 0 Normal exit status (no problems were encountered). X ! 1 The calling program specified the -#, the -U or the -M ! option to parseargs, or specified an argUsage flag on ! the command line. Only the appropriate message is X displayed. X X 2 A command line syntax error was encountered by *************** *** 848,868 **** X 4 A syntax error was encountered in the argument X specification string that was specified to parseargs. X - - - - - Page 13 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X FILES X /usr/local/parseargs.pl X This file defines a perl function named parseargs to --- 886,891 ---- *************** *** 892,897 **** --- 915,934 ---- X -f-arg X X will properly assign the string ``-arg'' to the option + + + + Page 14 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X whereas the following: X -f -arg X *************** *** 916,934 **** X Hence multiple ``leading dash'' arguments may specified as X follows: X - - - Page 14 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - X -f-dash_arg1 -f-dash_arg2 ... X X BUGS --- 953,958 ---- *************** *** 957,962 **** --- 981,1000 ---- X X Parseargs cannot properly preserve any newlines in shell X variables if the eval command is used to read its output + + + + Page 15 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + X (this is a shortcoming of the eval command, not of X parseargs). If the user is concerned about this particular X case, then the user should redirect the output from *************** *** 966,975 **** X or characters following a newline may be lost, in any X variables that are set by parseargs. X - Parseargs(1) is subject to the same caveats as parseargs(3). - Refer to the CAVEATS section of the parseargs(3) manual - page(s) for more information. - X AUTHOR X Brad Appleton (brad@ssd.csd.harris.com) X Harris Computer Systems, Fort Lauderdale, FL USA --- 1004,1009 ---- *************** *** 984,990 **** X X X ! Page 15 X X X --- 1018,1056 ---- X X X ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! Page 16 X X X *** /hx1d3/lp/brad/parseargs_patch03/parseargs/parseargs3.txt Wed Apr 10 09:56:01 1991 --- parseargs3.txt Mon Apr 15 08:31:33 1991 *************** *** 6,22 **** X X X NAME ! parseargs, usage - parse command line argument vectors X X SYNOPSIS X #include <parseargs.h> X ! int parseargs( char *argv[], ARGDESC *argd ) ! int fparseargs( FILE *fp, ARGDESC *argd ) ! int lparseargs( ArgList *argls, ARGDESC *argd ) ! int sparseargs( char *str, ARGDESC *argd ) ! int vparseargs( ARGDESC *argd, int argc, ... ) ! void usage( const ARGDESC *argd ) X X DESCRIPTION X Given a vector of string-valued arguments such as that --- 6,23 ---- X X X NAME ! parseargs - parse command line argument vectors X X SYNOPSIS X #include <parseargs.h> X ! int parseargs( char *argv[], ARGDESC *argd ); ! int fparseargs( FILE *fp, ARGDESC *argd ); ! int lparseargs( ArgList *argls, ARGDESC *argd ); ! int sparseargs( char *str, ARGDESC *argd ); ! int vparseargs( ARGDESC *argd, int argc, ... ); ! void usage( const ARGDESC *argd ); ! extern const char *ProgName; X X DESCRIPTION X Given a vector of string-valued arguments such as that *************** *** 27,50 **** X argument values that are syntactically incorrect. X X Given a readable input stream and an argdesc array, fpar- ! seargs will parse arguments in a file in much the same ! manner as parseargs. A maximum-line length of 255 charac- ! ters is imposed. NO ``escaping'' of any kind is performed. ! Comments of a limited form are permitted: if the first non- ! whitespace character on a line is a '#' (or '!' for VMS) ! then that entire line is considered a comment and is ! ignored. If a value is provided for an argument that is NOT ! a list or a vector, then the value MUST be on the same line ! as the argument (in other words, ``-v val'' is fine but ! ``-v\nval'' is a not). X X Given an ArgList and an argdesc array, lparseargs will parse ! arguments in an ArgList in much the same manner as par- ! seargs. X X Given a single string and an argdesc array, sparseargs will ! parse arguments from a string in much the same manner as ! parseargs. Sparseargs will split the given string up into a X vector of whitespace separated tokens and then attempt to X parse the resultant vector as if it were given as argv[] on X the command-line. NO special treatment is given to charac- --- 28,50 ---- X argument values that are syntactically incorrect. X X Given a readable input stream and an argdesc array, fpar- ! seargs will parse arguments in a file in the same manner as ! parseargs. A maximum-line length of 255 characters is ! imposed. NO ``escaping'' of any kind is performed. Comments ! of a limited form are permitted: if the first non-whitespace ! character on a line is a '#' (or '!' for VMS) then that ! entire line is considered a comment and is ignored. If a ! value is provided for an argument that is NOT a list or a ! vector, then the value MUST be on the same line as the argu- ! ment (in other words, ``-v val'' is fine but ``-v\nval'' is ! a not). X X Given an ArgList and an argdesc array, lparseargs will parse ! arguments in an ArgList in the same manner as parseargs. X X Given a single string and an argdesc array, sparseargs will ! parse arguments from a string in much the manner as par- ! seargs. Sparseargs will split the given string up into a X vector of whitespace separated tokens and then attempt to X parse the resultant vector as if it were given as argv[] on X the command-line. NO special treatment is given to charac- *************** *** 52,62 **** X Sparseargs will always assume that any whitespace characters X are intended as argument separators. X - X Vparseargs takes an argdesc array, the number of arguments X to parse, and a (possibly NULL terminated) list of ! argument-strings and parses them in much the same manner as ! parseargs. Unlike sparseargs, vparseargs assumes that all X X X --- 52,62 ---- X Sparseargs will always assume that any whitespace characters X are intended as argument separators. X X Vparseargs takes an argdesc array, the number of arguments X to parse, and a (possibly NULL terminated) list of ! argument-strings and parses them in the same manner as par- ! seargs. Unlike sparseargs, vparseargs assumes that all ! parameters are already split up into tokens, hence any X X X *************** *** 71,86 **** X X X ! parameters are already split up into tokens, hence any whi- ! tespace characters contained in any of the string-parameters ! are used as is (and will be considered a part of an argument ! name or value). X - X Given an argdesc array, usage will print the usage for the X given command in the format specified by the user's X USAGECNTL environment variable. X X THE ARGUMENT STRUCTURE X The basic type used by the parseargs library is the argument X descriptor (or "argdesc" for short). An ARGDESC structure is --- 71,90 ---- X X X ! whitespace characters contained in any of the string- ! parameters are used as is (and will be considered a part of ! an argument name or value). X X Given an argdesc array, usage will print the usage for the X given command in the format specified by the user's X USAGECNTL environment variable. X + After returning from any of the aforementioned functions, + the global string ProgName will contain the name of the com- + mand corresponding to the argument-descriptor array that was + most recently operated upon by one the functions in the par- + seargs(3) function library. + X THE ARGUMENT STRUCTURE X The basic type used by the parseargs library is the argument X descriptor (or "argdesc" for short). An ARGDESC structure is *************** *** 120,131 **** X this field must correspond to the name of one of the X argument type functions described in argtype(3). X - ARBPTR ad_valp; - This field is a generic pointer to the storage used to - represent the internal value of the command-line X X - X Page 2 X X --- 124,131 ---- *************** *** 137,149 **** X X X ! argument. It may be a pointer to a number, a boolean ! value, a string, a list, or anything else for which ! there exists a corresponding arg-type function to use ! in the ad_type field. In the case of of parseargs(1) ! this field must be the name of the corresponding shell ! variable which will eventually hold the value of the ! argument given on the command-line. X X const char *ad_prompt; X This field contains the long-name of the argument and --- 137,152 ---- X X X ! ARBPTR ad_valp; ! This field is a generic pointer to the storage used to ! represent the internal value of the command-line argu- ! ment. It may be a pointer to a number, a boolean value, ! a string, a list, or anything else for which there ! exists a corresponding arg-type function to use in the ! ad_type field. In the case of of parseargs(1) this ! field must be the name of the corresponding shell vari- ! able which will eventually hold the value of the argu- ! ment given on the command-line. X X const char *ad_prompt; X This field contains the long-name of the argument and *************** *** 155,161 **** X contains any uppercase characters, then the substring X of long-name consisting of all uppercase characters is X used as the argument keyword and the entire long-name ! is used as the name of the argument (if a value my be X supplied). The long-name may be matched by supplying a X unique prefix of either the argument keyword or the X argument name. --- 158,164 ---- X contains any uppercase characters, then the substring X of long-name consisting of all uppercase characters is X used as the argument keyword and the entire long-name ! is used as the name of the argument (if a value may be X supplied). The long-name may be matched by supplying a X unique prefix of either the argument keyword or the X argument name. *************** *** 173,179 **** X char *InFile; X char *OutFile = CHARNULL; X BOOL XRated = FALSE; ! struct namelist *Files = NULL; X X ARGDESC Args[] = X { --- 176,182 ---- X char *InFile; X char *OutFile = CHARNULL; X BOOL XRated = FALSE; ! ArgList *Files = ARGLISTNULL; X X ARGDESC Args[] = X { *************** *** 183,197 **** X ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}", X ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}", X 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}", ! ' ', ARGOPT|ARGLIST, argStr, __ &Files, "File {files to be read}", X ENDOFARGS X }; X X X - - - X Page 3 X X --- 186,197 ---- X ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}", X ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}", X 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}", ! ' ', ARGLIST, listStr, __ &Files, "File {files to be read}", X ENDOFARGS X }; X X X X Page 3 X X *************** *** 379,386 **** X arg_sdesc(ad) X Return the description of an argument. If a description X was supplied, the ARGDESCRIBED flag will be set and the ! description will immediately follow the terminating NUL ! byte of the string name. X X ARG_isDESCRIBED(ad) X Evaluates to TRUE only if an argument description was --- 379,386 ---- X arg_sdesc(ad) X Return the description of an argument. If a description X was supplied, the ARGDESCRIBED flag will be set and the ! description will immediately follow the terminating ! NULL byte of the string name. X X ARG_isDESCRIBED(ad) X Evaluates to TRUE only if an argument description was *************** *** 448,454 **** X usage messages. X X CMD MACROS ! Parseargs.h defines a set of macros to allow a more "self X documenting" approach to declaring argument-descriptor X arrays. The "old-style" is still accepted (but if used it is X recommended that the STARTOFARGS macro is used in conjunc- --- 448,454 ---- X usage messages. X X CMD MACROS ! <parseargs.h> defines a set of macros to allow a more "self X documenting" approach to declaring argument-descriptor X arrays. The "old-style" is still accepted (but if used it is X recommended that the STARTOFARGS macro is used in conjunc- *************** *** 606,625 **** X Ignore X Ignore any unrecognized or improperly specified X command-line arguments and continue execution of the ! program. Normally, if an argument is unmatched (or is ! improperly specified), a usage message is printed and ! program execution is terminated. X X OptsOnly X Under UNIX, setting this flag will disable the parsing X of long-option syntax. This will cause all arguments ! starting with '+' to always be treated as a positional X parameter (instead of a long-option). X X KwdsOnly X Under UNIX, setting this flag disables the parsing of X single-character options. This will cause all argu- ! ments starting with '-' to always be treated as a posi- X tional parameter (instead of an option). X X LoptsOnly --- 606,625 ---- X Ignore X Ignore any unrecognized or improperly specified X command-line arguments and continue execution of the ! program. Normally, if a required argument is unmatched ! (or an argument is improperly specified), a usage mes- ! sage is printed program execution is terminated. X X OptsOnly X Under UNIX, setting this flag will disable the parsing X of long-option syntax. This will cause all arguments ! starting with `+' to always be treated as a positional X parameter (instead of a long-option). X X KwdsOnly X Under UNIX, setting this flag disables the parsing of X single-character options. This will cause all argu- ! ments starting with `-' to always be treated as a posi- X tional parameter (instead of an option). X X LoptsOnly *************** *** 640,648 **** X positional argument. X X CaseIgnore ! Setting this flag causes character-case to be ignored ! when attempting to match single-character argument ! names (i.e. causes "-i" and "-I" will be considered X equivalent). X X If the environment variable ``PARSECNTL'' is empty or unde- --- 640,648 ---- X positional argument. X X CaseIgnore ! Setting this flag will cause character-case to be ! ignored when attempting to match single-character argu- ! ment names (i.e. causes "-i" and "-I" to be considered X equivalent). X X If the environment variable ``PARSECNTL'' is empty or unde- *************** *** 683,691 **** X ferred to as ``terse'' mode). The other two ``modes'' con- X trol the displaying of option syntax and long-option syntax. X A mode may be explicitly disabled by preceding its ! corresponding string with the `!' character. The ``modes'' ! which correspond to the possible values of the ``USAGECNTL'' ! environment variable are given by the following table. X X Quiet X No usage message of any kind is displayed. --- 683,692 ---- X ferred to as ``terse'' mode). The other two ``modes'' con- X trol the displaying of option syntax and long-option syntax. X A mode may be explicitly disabled by preceding its ! corresponding string with the `!' or `-' character. The ! ``modes'' which correspond to the possible values of the ! ``USAGECNTL'' environment variable are given by the follow- ! ing table. X X Quiet X No usage message of any kind is displayed. *************** *** 719,725 **** X X X - X Page 11 X X --- 720,725 ---- *************** *** 759,766 **** X vectors however need a set of flags for each item they con- X tain. Once an arg-list has been created, it may be deallo- X cated using the function listFree. ListFree takes one param- ! eter: first of which is the address of the first item in the ! arg-list. X X An alternative to argument-lists is argument vectors (or X arg-vectors). Arg-vectors use the ARGVEC flag instead of --- 759,765 ---- X vectors however need a set of flags for each item they con- X tain. Once an arg-list has been created, it may be deallo- X cated using the function listFree. ListFree takes one param- ! eter: the address of the first item in the arg-list. X X An alternative to argument-lists is argument vectors (or X arg-vectors). Arg-vectors use the ARGVEC flag instead of *************** *** 769,775 **** X responsible for handling vectors of its type (although some X argXxx functions such as the boolean types do not support X vectors). An arg-vector is a structure which contains a ! count, an array of elements (i.e. an argc/argv pair), and an X array of flags, one for each element of argv. There are two X macros in defined in <parseargs.h> which are used for arg- X vectors. ARGVEC_T may be used to declare a vector structure --- 768,774 ---- X responsible for handling vectors of its type (although some X argXxx functions such as the boolean types do not support X vectors). An arg-vector is a structure which contains a ! count, an array of elements (i.e. an argc,argv pair), and an X array of flags, one for each element of argv. There are two X macros in defined in <parseargs.h> which are used for arg- X vectors. ARGVEC_T may be used to declare a vector structure *************** *** 783,788 **** --- 782,788 ---- X X ( StrVec.array[ StrVec.count ] == (char *)NULL ) X + is always true, and character-vectors will always have an X X X *************** *** 797,803 **** X X X - is always true, and character-vectors will always have an X extra NUL-character at the end such that: X X ( CharVec.array[ CharVec.count ] == '\0' ) --- 797,802 ---- *************** *** 849,854 **** --- 848,854 ---- X printf( "String[%d]=%s, flags=%x\n", X i, StrVec.array[i], StrVec.flags[i] ); X + for ( i = 0 ; i < NumVec.count ; i++ ) X X X *************** *** 863,869 **** X X X - for ( i = 0 ; i < NumVec.count ; i++ ) X printf( "Number[%d]=%s, flags=%x\n", X i, NumVec.array[i], NumVec.flags[i] ); X --- 863,868 ---- *************** *** 884,901 **** X X BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf ) X ! The argd argument points to the descriptor for the argument ! being converted. Its main use is to find the location in ! which to store the converted value, located in ! argd->ad_valp. The string value to be converted is passed ! in vp (which will be NULL if the ARGNOVAL flag was set for ! the corresponding entry in the arg-descriptor table). The ! copyf flag is TRUE if the vp string value must be copied ! when saved. Most non-string types are copied implicitly ! (for example, integer arguments are stored in binary form, ! so the original string value need not be saved), so this ! argument can usually be ignored. Put simply, this flag is ! TRUE when vp points to a temporary buffer area. X X If the type function successfully converts the value, and X uses the entire value, it should return TRUE. If the type --- 883,900 ---- X X BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf ) X ! The ad argument points to the descriptor for the argument ! being converted. Its main use is to find the location in ! which to store the converted value, located in ad->ad_valp. ! The string value to be converted is passed in vp (which will ! be NULL if the ARGNOVAL flag was set for the corresponding ! entry in the arg-descriptor table). The copyf flag is TRUE ! if the vp string value must be copied when saved. Most SHAR_EOF true || echo 'restore of DOCPATCH failed' echo 'End of part 1' echo 'File DOCPATCH is continued in part 2' echo 2 > _shar_seq_.tmp exit 0 exit 0 # Just in case... -- Kent Landfield INTERNET: kent@sparky.IMD.Sterling.COM Sterling Software, IMD UUCP: uunet!sparky!kent Phone: (402) 291-8300 FAX: (402) 291-4362 Please send comp.sources.misc-related mail to kent@uunet.uu.net.